home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Add-Ons / MPW / MPW rman 1.3.4 / README-rman < prev    next >
Encoding:
Text File  |  1995-12-06  |  6.1 KB  |  136 lines  |  [TEXT/MPS ]
  1. This is a port of RosettaMan to MPW. To use it, simply drop the "rman" MPW Tool
  2. into the {MPW}Tools folder.
  3.  
  4. Please report bugs to 
  5.  
  6. neeri@iis.ee.ethz.ch
  7.  
  8. Matthias Neeracher
  9.  
  10. --------------
  11. ORIGINAL README:
  12. --------------
  13. *** INSTALLING ***
  14.  
  15. Set BINDIR in the Makefile to where you keep your binaries and MANDIR
  16. to where you keep your man pages (in their source form).  (If you're
  17. using RosettaMan with TkMan, BINDIR needs to be a component of your
  18. bin PATH.)  After properly editing the Makefile, type `make install'.
  19. Thereafter (perhaps after a `rehash') type `rman' to invoke RosettaMan.
  20. RosettaMan requires an ANSI C compiler.
  21.  
  22. If you send me bug reports and/or suggestions for new features,
  23. include the version of RosettaMan (available by typing `rman -v').
  24. RosettaMan doesn't parse every aspect of every man page perfectly, but
  25. if it blows up spectacularly where it doesn't seem like it should, you
  26. can send me the man page (or a representative man page if it blows up
  27. on a class of man pages) in BOTH: (1) [tn]roff source form, from
  28. .../man/manX and (2) formatted form (as formatted by `nroff -man'),
  29. uuencoded to preserve the control characters, from .../man/catX.
  30.  
  31. The home location for RosettaMan is ftp.cs.berkeley.edu:
  32. /ucb/people/phelps/tcltk/rman.tar.Z (this is a softlink to the latest,
  33. numbered version).  If you discover a bug and you obtained RosettaMan
  34. at some other site, first grab it from this one to see if the problem
  35. has been fixed.
  36.  
  37. --------------------------------------------------
  38.  
  39.  
  40. *** COPYRIGHT ***
  41.  
  42. Copyright (c) 1993-1994  T.A. Phelps  (phelps@cs.Berkeley.EDU)
  43. All Rights Reserved.
  44.  
  45. Permission to use, copy, modify, and distribute this software and its
  46. documentation for educational, research and non-profit purposes, 
  47. without fee, and without a written agreement is hereby granted, 
  48. provided that the above copyright notice and the following three 
  49. paragraphs appear in all copies.  
  50.  
  51. Permission to incorporate this software into commercial products may 
  52. be obtained from the Office of Technology Licensing, 2150 Shattuck 
  53. Avenue, Suite 510, Berkeley, CA  94704. 
  54.  
  55. IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  56. FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  57. ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
  58. THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
  59. SUCH DAMAGE.
  60.  
  61. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  62. INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  63. MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
  64. PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
  65. CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
  66. ENHANCEMENTS, OR MODIFICATIONS.
  67.  
  68. --------------------------------------------------
  69.  
  70.  
  71. *** SYNOPSIS ***
  72.  
  73. RosettaMan is a filter for UNIX manual pages.  It takes as input man
  74. pages formatted for a variety of UNIX flavors (not [tn]roff source)
  75. and produces as output a variety of file formats.  Currently
  76. RosettaMan accepts man pages as formatted by the following flavors of
  77. UNIX: Hewlett-Packard HP-UX, AT&T System V, SunOS, Sun Solaris, OSF/1,
  78. DEC Ultrix, SGI IRIX, Linux, SCO; and produces output for the following
  79. formats: printable ASCII only (stripping page headers and footers),
  80. section and subsection headers only, TkMan, [tn]roff, Ensemble,
  81. SGML (soon--I finally found a DTD), HTML, LaTeX, RTF, Perl 5's pod.
  82.  
  83. RosettaMan improves on other man page filters in several ways: (1) its
  84. analysis recognizes the structural pieces of man pages, enabling high
  85. quality output, (2) its modular structure permits easy augmentation of
  86. output formats, (3) it accepts man pages formatted with the varient
  87. macros of many different flavors of UNIX, and (4) it doesn't require
  88. modification or cooperation with any other program.
  89.  
  90. RosettaMan is a rewrite of TkMan's man page filter, called bs2tk.  (If
  91. you haven't heard about TkMan, a hypertext man page browser, you
  92. should grab it via anonymous ftp from ftp.cs.berkeley.edu:
  93. /ucb/people/phelps/tkman.tar.Z.)  Whereas bs2tk generated output only for
  94. TkMan, RosettaMan generalizes the process so that the analysis can be
  95. leveraged to new output formats.  A single analysis engine recognizes
  96. section heads, subsection heads, body text, lists, references to other
  97. man pages, boldface, italics, bold italics, special characters (like
  98. bullets), tables (to a degree) and strips out page headers and
  99. footers.  The engine sends signals to the selected output functions so
  100. that an enhancement in the engine improves the quality of output of
  101. all of them.  Output format functions are easy to add, and thus far
  102. average about about 75 lines of C code each.
  103.  
  104.  
  105.  
  106. *** NOTES ON CURRENT VERSION ***
  107.  
  108. Help!  I'm looking for people to help with the following projects.
  109. (1) Better RTF output format.  The current one works, but could be
  110. made better.  (2) FrameMaker MIF output format.  It should be easy to
  111. write, if you're familiar with MIF. (3) Roff macros that produce text
  112. that is easily parsable.  RosettaMan handles a great variety, but some
  113. things, like H-P's tables, are intractable.  If you write an output
  114. format or otherwise improve RosettaMan, please send in your code so
  115. that I may share the wealth in future releases.
  116.  
  117. This version can try to identify tables (turn this on with the -T
  118. switch) by looking for lines with a large amount of interword spacing,
  119. reasoning that this is space between columns of a table.  This
  120. heuristic doesn't always work and sometimes misidentifies ordinary
  121. text as tables.  In general I think it is impossible to perfectly
  122. identify tables from nroff formatted text.  However, I do think the
  123. heuristics can be tuned, so if you have a collection of manual pages
  124. with unrecognized tables, send me the lot, in formatted form (i.e.,
  125. after formatting with nroff -man), and uuencode them to preserve the
  126. control characters.  Better, if you can think of heuristics that
  127. distinguish tables from ordinary text, I'd like to hear them.
  128.  
  129.  
  130. Notes for HTML consumers: This filter does real (heuristic)
  131. parsing--no <PRE>!  Man page references are turned into hypertext links.
  132.  
  133. Several people have extended World Wide Web servers to format man
  134. pages on the fly.  Check the README file in the contrib directory for
  135. a list.
  136.